<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title>Getting Started</title>
</head>

<body>

<h2>Getting Started</h2>

<h3>Write a textual story</h3>

<p>Create a textual story file with a name that expresses the
behaviour to verify, e.g. <b>i_can_toggle_a_cell.story</b> and define
steps in it:</p>
<pre class="brush: bdd">
Given a 5 by 5 game
When I toggle the cell at (2, 3)
Then the grid should look like
.....
.....
.....
..X..
.....
When I toggle the cell at (2, 4)
Then the grid should look like
.....
.....
.....
..X..
..X..
When I toggle the cell at (2, 3)
Then the grid should look like
.....
.....
.....
.....
..X..
</pre>
<p>Steps must start with one of the keywords highlighted (see <a
	href="concepts.html">Concepts</a> for more details) and are not limited
to a single line. Also, unless otherwise indicated, a story has at least
one implicit scenario, each of which is a collection of steps.</p>

<h3>Map steps to Java methods</h3>

<p>Define your <b>GridSteps</b> class, a simple POJO, which will contain the Java
methods that are mapped to the textual steps. The methods need to
annotated with one of the JBehave <a
	href="javadoc/core/org/jbehave/core/annotations/package-summary.html">annotations</a>
and the annotated value should contain a regex pattern that matches the
textual step:</p>

<script type="syntaxhighlighter" class="brush: java">
<![CDATA[
public class GridSteps { // Look, Ma', I'm a POJO!
    
    private Game game;
    private StringRenderer renderer;

    @Given("a $width by $height game")
    @Aliases(values={"a new game: $width by $height"})
    public void theGameIsRunning(int width, int height) {
        game = new Game(width, height);
        renderer = new StringRenderer();
        game.setObserver(renderer);
    }
    
    @When("I toggle the cell at ($column, $row)")
    public void iToggleTheCellAt(int column, int row) {
        game.toggleCellAt(column, row);
    }
    
    @Then("the grid should look like $grid")
    @Aliases(values={"the grid should be $grid"})
    public void theGridShouldLookLike(String grid) {
        assertThat(renderer.asString(), equalTo(grid));
    }

}
]]>
</script>

<h3>Configure a Java Embeddable class</h3>

<p>Define your <a
	href="javadoc/core/org/jbehave/core/Embeddable.html">Embeddable</a>
class which provides the link between the JBehave's executor framework (called <a
    href="javadoc/core/org/jbehave/core/Embedder.html">Embedder</a>) and the textual stories.
The simplest configuration is a one-to-one mapping between a Java class and a textual story file.  
So we'll extend <a
	href="javadoc/core/org/jbehave/core/junit/JUnitStory.html">JUnitStory</a> and give it 
a name that can be (conventionally) mapped to the textual story filename, e.g. <b>ICanToggleACell.java</b>:</p>

<script type="syntaxhighlighter" class="brush: java">
<![CDATA[
public class ICanToggleACell extends JUnitStory {

    // Here we specify the configuration, starting from default MostUsefulConfiguration, and changing only what is needed
    @Override
    public Configuration configuration() {
        return new MostUsefulConfiguration()
            // where to find the stories
            .useStoryLoader(new LoadFromClasspath(this.getClass()))  
            // CONSOLE and TXT reporting
            .useStoryReporterBuilder(new StoryReporterBuilder().withDefaultFormats().withFormats(Format.CONSOLE, Format.TXT)); 
    }

    // Here we specify the steps classes
    @Override
    public InjectableStepsFactory stepsFactory() {        
        // varargs, can have more that one steps classes
        return new InstanceStepsFactory(configuration(), new GridSteps());
    }
}
]]>
</script>
<p>The story is now configured to use the <b>GridSteps</b> that defines mappings between the textual steps and the Java methods to 
be executed.</p>

<h3>Run story</h3>

<p>Open your favourite IDE, the <b>ICanToggleACell.java</b> class
will allow itself to run as a <a href="http://junit.org">JUnit</a> test.
Be sure to check that you have all the required <a
	href="dependencies.html">dependencies</a> in your classpath.</p>

<h3>View generated reports</h3>

<p>Since we've defined two reports, CONSOLE and TXT, you should see during the running of the story
 the output being written the <b>System.out</b>.  In addition, the same output will also have been written
 to a file in <b>target/jbehave</b>.</p>

<h2>Next?</h2>

<span class="followup">JBehave development has been
example-driven and it is very instructive to go through one or more
working examples in the source repository, which illustrate the features of JBehave.  
The <b>gameoflife</b> example contains much of the above and is ready to be run. 
Be sure to read about <a href="running-examples.html">running examples</a> and <a
	href="running-stories.html">running stories</a>.</span>

</body>
</html>